docs: enhance task creation authentication details by pradipthaadhi · Pull Request #115 · recoupable/docs

pradipthaadhi · 2026-04-07T21:21:13Z

Added section on identity binding for task creation in authentication documentation.
Updated OpenAPI specification to clarify authentication requirements and error responses for POST /api/tasks.
Revised task creation documentation to emphasize the need for server-derived account identity and the handling of account_id authorization checks.

Summary by CodeRabbit

Documentation
- Task creation API endpoint now requires authentication via API key or Bearer token
- Additional error response codes documented (401 Unauthorized, 403 Forbidden, 400 Bad Request, 500 Server Error) with detailed descriptions
- Account ID validation behavior and requirements now explicitly documented

- Added section on identity binding for task creation in authentication documentation. - Updated OpenAPI specification to clarify authentication requirements and error responses for `POST /api/tasks`. - Revised task creation documentation to emphasize the need for server-derived account identity and the handling of `account_id` authorization checks.

coderabbitai · 2026-04-07T21:21:27Z

📝 Walkthrough

Walkthrough

The OpenAPI specification for POST /api/tasks has been updated to formally document authentication requirements using API key or Bearer token authentication, server-side identity derivation, and account_id authorization with corresponding 401 and 403 error responses.

Changes

Cohort / File(s)	Summary
OpenAPI Endpoint Documentation `api-reference/openapi.json`	Updated `POST /api/tasks` operation to document authentication requirements (apiKeyAuth, bearerAuth), clarified server-side identity derivation and account_id validation, added 401 (invalid/missing credentials) and 403 (unauthorized account_id) responses, and refined request body and field descriptions to reflect authorization behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

sweetmantech

Poem

🐰 The docs now speak with clarity bright,
Authentication takes its rightful flight,
With 401s and 403s in tow,
The API's rules let callers know,
Account validation—no more guessing tonight! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: enhance task creation authentication details' directly and clearly summarizes the main change: updating OpenAPI documentation to improve authentication clarity for POST /api/tasks.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch yuliusupwork/myc-4583-docs-require-auth-identity-bound-ownership-for-post-apitasks

⚔️ Resolve merge conflicts

Resolve merge conflict in branch yuliusupwork/myc-4583-docs-require-auth-identity-bound-ownership-for-post-apitasks

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@api-reference/openapi.json`:
- Around line 81-89: The OpenAPI contract for POST /api/tasks is inconsistent:
the operation description says account_id is optional and only validated if
provided, but the CreateTaskRequest schema (CreateTaskRequest) currently marks
account_id as required, and the description says the success body is an array
while TasksResponse is defined as an object with a tasks array; fix by aligning
schemas and description—either make account_id optional in CreateTaskRequest
(remove it from required) if callers may omit it, or update the operation text
to require and validate account_id if you intend it required; likewise ensure
the response shape matches: change the operation description to state it returns
a TasksResponse object (with tasks array) or update TasksResponse to be an array
type matching the described response; update the textual description of POST
/api/tasks to exactly reflect the chosen schema changes.

In `@api-reference/tasks/create.mdx`:
- Around line 6-10: The api-reference/tasks/create.mdx page contains body
content that must be removed and kept frontmatter-only; delete the descriptive
paragraphs (e.g., the "Creates a scheduled task." block and the text about
authentication and account_id) and move that information into the OpenAPI
operation description for the Create Task operation (or into authentication.mdx)
so the OpenAPI spec is the single source of truth; ensure references to
account_id and the 403 behavior are documented in the OpenAPI operation
description rather than in api-reference/tasks/create.mdx.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 00021b8f-c3e9-4fb6-b63d-fae85feb5e08

📥 Commits

Reviewing files that changed from the base of the PR and between 7882837 and 68076d1.

📒 Files selected for processing (3)

api-reference/openapi.json
api-reference/tasks/create.mdx
authentication.mdx

api-reference/openapi.json

api-reference/tasks/create.mdx

cubic-dev-ai

2 issues found across 3 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/tasks/create.mdx">

<violation number="1" location="api-reference/tasks/create.mdx:6">
P2: Keep API reference MDX pages frontmatter-only; move this endpoint text into `openapi.json` instead.</violation>
</file>

<file name="api-reference/openapi.json">

<violation number="1" location="api-reference/openapi.json:81">
P1: The description says "If account_id is provided…" implying it's optional, but `CreateTaskRequest` still lists `account_id` in the `required` array. This inconsistency will cause generated SDKs and docs to contradict each other. Either remove `account_id` from `required` (and update its property description to say it's optional/server-derived), or reword this description to reflect that it is always required.

Also, "an array containing the created task" is inaccurate — `TasksResponse` is an object with a `tasks` array, not a bare array. Consider: `The response shape matches the GET endpoint (TasksResponse, with the created task in the tasks array).`</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

api-reference/openapi.json

api-reference/tasks/create.mdx

- Removed outdated section on identity binding from authentication documentation. - Enhanced OpenAPI specification for `POST /api/tasks` to clarify authentication methods and authorization checks for `account_id`. - Updated task creation documentation to emphasize the need for server-derived account identity and the implications of `account_id` validation.

coderabbitai

♻️ Duplicate comments (1)

api-reference/openapi.json (1)

81-91: ⚠️ Potential issue | 🟠 Major

Don't require account_id if the server is meant to derive it.

This is internally consistent now, but it still removes the identity-derived path described by this PR: CreateTaskRequest requires account_id, so generated docs/SDKs will force callers to send it even when the server could derive the target account from credentials. If only overrides are meant to be authorized, make account_id optional in the schema and update the description to say it is validated only when provided.

🛠️ Suggested contract update

         "description": "Create a new scheduled task. Authentication is required (`x-api-key` or `Authorization: Bearer`). The server derives caller identity from credentials and authorizes the required body field `account_id` using the same account override rules as elsewhere (self-access or permitted organization access). A body `account_id` outside the caller's authorized scope returns 403 Forbidden. On success, returns HTTP 200 with a `TasksResponse` object: `status: success` and a `tasks` array containing the created task (same envelope as GET /api/tasks). Missing or invalid authentication returns 401.",
+        "description": "Create a new scheduled task. Authentication is required (`x-api-key` or `Authorization: Bearer`). The server derives caller identity from credentials and, if `account_id` is provided, authorizes it using the same account override rules as elsewhere (self-access or permitted organization access). A body `account_id` outside the caller's authorized scope returns 403 Forbidden. On success, returns HTTP 200 with a `TasksResponse` object: `status: success` and a `tasks` array containing the created task (same envelope as GET /api/tasks). Missing or invalid authentication returns 401.",
...
         "required": [
           "title",
           "prompt",
           "schedule",
-          "account_id",
           "artist_account_id"
         ],
...
-            "description": "Required. UUID of the Recoup account under which this task is created. Must match the authenticated caller's own account or an account the caller is authorized to act for (organization override rules); otherwise the API returns 403. This field is not proof of ownership by itself—it is validated against credentials server-side.",
+            "description": "Optional. UUID of the Recoup account under which this task is created. If omitted, the server derives it from the authenticated credentials. If provided, it must match the authenticated caller's own account or an account the caller is authorized to act for (organization override rules); otherwise the API returns 403. This field is not proof of ownership by itself—it is validated against credentials server-side.",

Also applies to: 7444-7473

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api-reference/openapi.json` around lines 81 - 91, The OpenAPI contract
currently forces callers to supply account_id even though the server can derive
identity; update the CreateTaskRequest schema to make the account_id property
optional (remove it from required[] or mark as nullable/optional in the schema)
and revise the POST /api/tasks requestBody/description to state that account_id
is optional and will be validated only when provided (otherwise the server
derives it from credentials); apply the same change to any other occurrences of
CreateTaskRequest usage in the spec (e.g., the duplicate block referenced) so
generated docs/SDKs no longer mandate account_id.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@api-reference/openapi.json`:
- Around line 81-91: The OpenAPI contract currently forces callers to supply
account_id even though the server can derive identity; update the
CreateTaskRequest schema to make the account_id property optional (remove it
from required[] or mark as nullable/optional in the schema) and revise the POST
/api/tasks requestBody/description to state that account_id is optional and will
be validated only when provided (otherwise the server derives it from
credentials); apply the same change to any other occurrences of
CreateTaskRequest usage in the spec (e.g., the duplicate block referenced) so
generated docs/SDKs no longer mandate account_id.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7573379a-f1b8-430a-ba5d-afdc4f66f8a9

📥 Commits

Reviewing files that changed from the base of the PR and between 68076d1 and 8b4d743.

📒 Files selected for processing (1)

api-reference/openapi.json

pradipthaadhi requested a review from sweetmantech as a code owner April 7, 2026 21:21

coderabbitai bot reviewed Apr 7, 2026

View reviewed changes

api-reference/openapi.json Outdated Show resolved Hide resolved

api-reference/tasks/create.mdx Outdated Show resolved Hide resolved

cubic-dev-ai bot reviewed Apr 7, 2026

View reviewed changes

api-reference/openapi.json Outdated Show resolved Hide resolved

api-reference/tasks/create.mdx Outdated Show resolved Hide resolved

coderabbitai bot reviewed Apr 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: enhance task creation authentication details#115

docs: enhance task creation authentication details#115
pradipthaadhi wants to merge 2 commits intomainfrom
yuliusupwork/myc-4583-docs-require-auth-identity-bound-ownership-for-post-apitasks

pradipthaadhi commented Apr 7, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Apr 7, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

pradipthaadhi commented Apr 7, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Poem

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

pradipthaadhi commented Apr 7, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Apr 7, 2026 •

edited

Loading